API GatewayのAPIキーと使用量プランについて調べてみた

#Amazon API Gateway

#AWS

小倉功一

2020.07.14

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

CX事業本部の小倉です。

API GatewayのAPIキー&使用量プラン機能について調べる機会があったのでまとめてみました。

何ができるの？

API GatewayからAPIキーを発行することで、以下が可能になります。

APIキーを持つユーザのみアクセス可能なAPIを作成できる
使用量プランを作成することで、APIキーにクォータ（アクセス可能回数）、レート（アクセス頻度）、バーストを設定できる
- （レート、バーストの制限値はAWSアカウント全体、APIステージ毎にも元々存在します）
APIキー毎のアクセス回数を取得できる

やってみる

API GatewayがAPIキーを受け取る方法は、ヘッダ経由とLambdaオーソライザ経由の二種類があるようです。
今回はヘッダ(x-api-key)から受け取る方法で作成してみます。

REST APIを作成

マネジメントコンソールからREST APIを作成します。 api-key-test という名前で作成しました。

作成したAPIに、/testというリソースを追加し、GETメソッドを作成します。
テスト用のLambda関数を呼び出すように設定しておきます。

GETメソッドのメソッドリクエストを選択して、APIキーの必要性をtrueに変更します。

これでこのメソッドは実行時にAPIキーが必要なメソッドになりました。 APIをデプロイして確認してみます。
（リクエストの送信にはIntelliJ IDEAのHTTPクライアントを使用しました）

devステージにデプロイし、/testへリクエストを送信すると、応答が403 Forbiddenとなりました。

APIキーの作成

それではAPIキーを作成します。 API Gateway -> APIキー -> APIキーの作成から、APIキーを作成します。

作成後の画面を確認してみると、APIキーが発行されているのがわかります。
（まだこの段階では先程作成した/testにはアクセスできません）

使用量プランの作成

次に使用量プランを作成します。
使用量プランの作成では、レート（1秒あたりのリクエスト数）や、
クォータ（特定の期間(日or週or月）内のリクエスト可能数）を設定することが出来ます。
今回は一日10回のリクエスト数制限を設定してみました。

今回は設定していませんが、使用量プランの中で更にリソース・メソッド毎にレート、バーストの設定をすることもできるようです。

使用量プラン、APIステージ、APIキーの関連付けを設定

使用量プランをAPIをAPIのステージに関連付けます。
先程作成した使用量プランを、devステージに関連付けました。

次に、使用量プランとAPIキーを関連付けます。
先程作成した使用量プランを、作成しておいたtest-api-keyと関連付けます。

ここまでで、以下の内容を準備しました。

APIステージ	使用量プラン	APIキー
dev	ベーシック（1日10回）	test-api-key

アクセスしてみる

それではもう一度APIにアクセスしてみます。リクエストヘッダx-api-keyに、作成したAPIキーの値を指定して送信します。

今度は無事に成功の応答が返却されてきました。

アクセス回数を取得してみる

APIキー毎のアクセス回数は、期間を指定しJSON形式、CSV形式でダウンロードすることが可能です。

JSON形式の場合、1つ目の値はアクセス回数、2つ目はアクセス可能回数の残数です。

CSV形式の場合は、クォータの値と、アクセス回数で出力されました。

この日付はUTCとなります。またアクセスしてから反映されるまで少し時間が掛かる場合があるようです。

アクセス回数を追加する

アクセス回数がクォータの値に達すると、以降のリクエストではエラーが応答されるようになります。
こうなった場合、リクエスト可能な数を追加することで再びアクセス可能になります。

使用量プランの挙動について

使用量プランによる制限は、使用量プランとAPIキーの組み合わせに対して実行されます。

複数のAPIキーを一つのプランに関連付けた場合、APIキー単位に制限が行われます。

APIステージ	使用量プラン	APIキー	アクセス可能数
dev	ベーシック（1日10回）	test-api-key-1	1日10回
dev	ベーシック（1日10回）	test-api-key-2	1日10回

異なるAPIステージで、同じ使用量プランとAPIキーを設定した場合、アクセス可能数は共有されます。

APIステージ	使用量プラン	APIキー
dev	ベーシック（1日10回）	test-api-key
prod	ベーシック（1日10回）	test-api-key

この場合、2つのステージで合計1日10回アクセス可能です。

ステージが別であれば同じAPIキーに異なる使用量プランを設定可能です。
開発環境ならば無制限にアクセス可能、というような設定が可能です。
（同じステージ内で、APIキーを複数の使用量プランに関連付けることはできません。）

APIステージ	使用量プラン	APIキー
dev	開発用（無制限）	test-api-key
prod	プレミアム（1日100回）	test-api-key

気をつけたいポイント

使用量プランの変更

APIキーに関連付けたプランを変更しようとすると、一度現在のプランとの関連付けを削除しないと
新しいプランとの関連付けを設定できませんでした。
ただし関連付けを削除してしまうと、過去の使用量プランでのアクセス数は取得できなくなりました。
APIキー提供先に対して使用量プランを変更する場合は、新たなAPIキーを発行したほうがよさそうです。